home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kstringhandler.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-10-08  |  18.1 KB  |  442 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 1999 Ian Zepp (icszepp@islc.net)
  3.    Copyright (C) 2000 Rik Hemsley (rikkus) <rik@kde.org>
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License version 2 as published by the Free Software Foundation.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19. #ifndef KSTRINGHANDLER_H
  20. #define KSTRINGHANDLER_H
  21.  
  22. #include <qstring.h>
  23. #include <qstringlist.h>
  24. #include <qregexp.h>            // for the word ranges
  25. #include <qfontmetrics.h>
  26. #include "kdelibs_export.h"
  27.  
  28. /**
  29.  * This class contains utility functions for handling strings.
  30.  *
  31.  * This class is @em not a substitute for the QString class. What
  32.  * I tried to do with this class is provide an easy way to
  33.  * cut/slice/splice words inside sentences in whatever order desired.
  34.  * While the main focus of this class are words (ie characters
  35.  * separated by spaces/tabs), the two core functions here ( split()
  36.  * and join() ) will function given any char to use as a separator.
  37.  * This will make it easy to redefine what a 'word' means in the
  38.  * future if needed.
  39.  *
  40.  * I freely stole some of the function names from python. I also think
  41.  * some of these were influenced by mIRC (yes, believe it if you will, I
  42.  * used to write a LOT of scripts in mIRC).
  43.  *
  44.  * The ranges are a fairly powerful way of getting/stripping words from
  45.  * a string. These ranges function, for the large part, as they would in
  46.  * python. See the word(const QString&, const char *) and remword(const QString&, uint) functions for more detail.
  47.  *
  48.  * This class contains no data members of its own. All strings are cut
  49.  * on the fly and returned as new qstrings/qstringlists.
  50.  *
  51.  * Quick example on how to use:
  52.  *
  53.  * \code
  54.  * KStringHandler kstr;
  55.  * QString line = "This is a test of the strings";
  56.  *
  57.  * cout << "1> " << kstr.word( line , "4:" ) << "\n";
  58.  * cout << "2> " << kstr.remrange( line , "2:5" ) << "\n";
  59.  * cout << "2> " << kstr.reverse( line ) << "\n";
  60.  * cout << "2> " << kstr.center( kstr.word( line , 4 ) , 15 ) << "\n";
  61.  * \endcode
  62.  *
  63.  * and so forth.
  64.  *
  65.  * @short Class for manipulating words and sentences in strings
  66.  * @author Ian Zepp <icszepp@islc.net>
  67.  * @see KShell
  68.  */
  69. class KDECORE_EXPORT KStringHandler
  70. {
  71. public:
  72.     /** Returns the nth word in the string if found
  73.       * Returns a EMPTY (not null) string otherwise.
  74.       * Note that the FIRST index is 0.
  75.       * @param text the string to search for the words
  76.       * @param pos the position of the word to search
  77.       * @return the word, or an empty string if not found
  78.       * @deprecated use QString::section instead
  79.       */
  80.     static QString        word( const QString &text , uint pos ) KDE_DEPRECATED;
  81.  
  82.     /** Returns a range of words from that string.
  83.       * Ie:
  84.       * @li "0" returns the very first word
  85.       * @li "0:" returns the first to the last word
  86.       * @li "0:3" returns the first to fourth words
  87.       * @li ":3" returns everything up to the fourth word
  88.       *
  89.       * If you grok python, you're set.
  90.       * @param text the string to search for the words
  91.       * @param range the words to return (see description)
  92.       * @return the words, or an empty string if not found
  93.       */
  94.     static QString        word( const QString &text , const char *range );
  95.  
  96.     /** Inserts a word into the string, and returns
  97.       * a new string with the word included. the first
  98.       * index is zero (0). If there are not @p pos words in the original
  99.       * string, the new word will be appended to the end.
  100.       * @param text the original text
  101.       * @param word the word to insert
  102.       * @param pos the position (in words) for the new word
  103.       * @return the resulting string
  104.       */
  105.     static QString        insword( const QString &text , const QString &word , uint pos );
  106.  
  107.     /** Replaces a word in the string, and returns
  108.       * a new string with the word included. the first
  109.       * index is zero (0). If there are not @p pos words in the original
  110.       * string, the new word will be appended to the end.
  111.       * @param text the original text
  112.       * @param word the word to insert
  113.       * @param pos the position (in words) for the new word
  114.       * @return the resulting string
  115.       */
  116.     static QString        setword( const QString &text , const QString &word , uint pos );
  117.  
  118.     /** Removes a word or ranges of words from the string,
  119.       * and returns a new string. The ranges definitions
  120.       * follow the definitions for the word() function.
  121.       *
  122.       * @li "0"        removes the very first word
  123.       * @li "0:"    removes the first the the last word
  124.       * @li "0:3"    removes the first to fourth words
  125.       * @li ":3"    removes everything up to the fourth word
  126.       * @param text the original text
  127.       * @param range the words to remove (see description)
  128.       * @return the resulting string
  129.       */
  130.     static QString        remrange( const QString &text , const char *range );
  131.  
  132.  
  133.     /** Removes a word at the given index, and returns a
  134.       * new string. The first index is zero (0).
  135.       * @param text the original text
  136.       * @param pos the position (in words) of thw word to delete
  137.       * @return the resulting string
  138.       */
  139.     static QString        remword( const QString &text , uint pos );
  140.  
  141.     /** Removes a matching word from the string, and returns
  142.       * a new string. Note that only ONE match is removed.
  143.       * @param text the original text
  144.       * @param word the word to remove
  145.       * @return the resulting string
  146.       */
  147.     static QString        remword( const QString &text , const QString &word );
  148.  
  149.     /** Capitalizes each word in the string
  150.       * "hello there" becomes "Hello There"        (string)
  151.       * @param text the text to capitalize
  152.       * @return the resulting string
  153.       */
  154.     static QString        capwords( const QString &text );
  155.  
  156.     /** Capitalizes each word in the list
  157.       * [hello, there] becomes [Hello, There]    (list)
  158.       * @param list the list to capitalize
  159.       * @return the resulting list
  160.       */
  161.     static QStringList    capwords( const QStringList &list );
  162.  
  163.     /** Reverses the order of the words in a string
  164.       * "hello there" becomes "there hello"        (string)
  165.       * @param text the text to reverse
  166.       * @return the resulting string
  167.       */
  168.     static QString        reverse( const QString &text );
  169.  
  170.     /** Reverses the order of the words in a list
  171.       * [hello, there] becomes [there, hello]    (list)
  172.       * @param list the list to reverse
  173.       * @return the resulting list
  174.       */
  175.     static QStringList    reverse( const QStringList &list );
  176.  
  177.     /** Left-justifies a string and returns a string at least 'width' characters
  178.       * wide.
  179.       * If the string is longer than the @p width, the original
  180.       * string is returned. It is never truncated.
  181.       * @param text the text to justify
  182.       * @param width the desired width of the new string
  183.       * @return the resulting string
  184.       * @deprecated use QString::leftJustify instead
  185.       */
  186.     static QString        ljust( const QString &text , uint width ) KDE_DEPRECATED;
  187.  
  188.     /** Right-justifies a string and returns a string at least 'width' characters
  189.       * wide.
  190.       * If the string is longer than the @p width, the original
  191.       * string is returned. It is never truncated.
  192.       * @param text the text to justify
  193.       * @param width the desired width of the new string
  194.       * @return the resulting string
  195.       * @deprecated use QString::rightJustify instead
  196.       */
  197.     static QString        rjust( const QString &text , uint width ) KDE_DEPRECATED;
  198.  
  199.     /** Centers a string and returns a string at least 'width' characters
  200.       * wide.
  201.       * If the string is longer than the @p width, the original
  202.       * string is returned. It is never truncated.
  203.       * @param text the text to justify
  204.       * @param width the desired width of the new string
  205.       * @return the resulting string
  206.       */
  207.     static QString        center( const QString &text , uint width );
  208.  
  209.     /** Substitute characters at the beginning of a string by "...".
  210.      * @param str is the string to modify
  211.      * @param maxlen is the maximum length the modified string will have
  212.      * If the original string is shorter than "maxlen", it is returned verbatim
  213.      * @return the modified string
  214.      */
  215.     static QString        lsqueeze( const QString & str, uint maxlen = 40 );
  216.  
  217.     /** Substitute characters at the beginning of a string by "...". Similar to
  218.      * method above, except that it truncates based on pixel width rather than
  219.      * the number of characters
  220.      * @param name is the string to modify
  221.      * @param fontMetrics is the font metrics to use to calculate character sizes
  222.      * @param maxlen is the maximum length in ems the modified string will have
  223.      * If the original string is shorter than "maxlen", it is returned verbatim
  224.      * @return the modified string
  225.      * @since 3.2
  226.      */
  227.     static QString lEmSqueeze( const QString & name,
  228.                                const QFontMetrics& fontMetrics,
  229.                                uint maxlen = 30 );
  230.  
  231.     /** Substitute characters at the beginning of a string by "...". Similar to
  232.      * method above, except that maxlen is the width in pixels to truncate to
  233.      * @param name is the string to modify
  234.      * @param fontMetrics is the font metrics to use to calculate character sizes
  235.      * @param maxPixels is the maximum pixel length the modified string will have
  236.      * If the original string is shorter than "maxlen", it is returned verbatim
  237.      * @return the modified string
  238.      * @since 3.2
  239.      */
  240.     static QString lPixelSqueeze( const QString & name,
  241.                                   const QFontMetrics& fontMetrics,
  242.                                   uint maxPixels );
  243.  
  244.     /** Substitute characters at the middle of a string by "...".
  245.      * @param str is the string to modify
  246.      * @param maxlen is the maximum length the modified string will have
  247.      * If the original string is shorter than "maxlen", it is returned verbatim
  248.      * @return the modified string
  249.      */
  250.     static QString        csqueeze( const QString & str, uint maxlen = 40 );
  251.  
  252.     /** Substitute characters in the middle of a string by "...". Similar to
  253.      * method above, except that it truncates based on pixel width rather than
  254.      * the number of characters
  255.      * @param name is the string to modify
  256.      * @param fontMetrics is the font metrics to use to calculate character sizes
  257.      * @param maxlen is the maximum length in ems the modified string will have
  258.      * If the original string is shorter than "maxlen", it is returned verbatim
  259.      * @return the modified string
  260.      * @since 3.2
  261.      */
  262.     static QString cEmSqueeze( const QString & name,
  263.                                const QFontMetrics& fontMetrics,
  264.                                uint maxlen = 30 );
  265.  
  266.     /** Substitute characters in the middle of a string by "...". Similar to
  267.      * method above, except that maxlen is the width in pixels to truncate to
  268.      * @param name is the string to modify
  269.      * @param fontMetrics is the font metrics to use to calculate character sizes
  270.      * @param maxPixels is the maximum pixel length the modified string will have
  271.      * If the original string is shorter than "maxlen", it is returned verbatim
  272.      * @return the modified string
  273.      * @since 3.2
  274.      */
  275.     static QString cPixelSqueeze( const QString & name,
  276.                                   const QFontMetrics& fontMetrics,
  277.                                   uint maxPixels );
  278.  
  279.     /** Substitute characters at the end of a string by "...".
  280.      * @param str is the string to modify
  281.      * @param maxlen is the maximum length the modified string will have
  282.      * If the original string is shorter than "maxlen", it is returned verbatim
  283.      * @return the modified string
  284.      */
  285.     static QString        rsqueeze( const QString & str, uint maxlen = 40 );
  286.  
  287.     /** Substitute characters at the end of a string by "...". Similar to
  288.      * method above, except that it truncates based on pixel width rather than
  289.      * the number of characters
  290.      * @param name is the string to modify
  291.      * @param fontMetrics is the font metrics to use to calculate character sizes
  292.      * @param maxlen is the maximum length in ems the modified string will have
  293.      * If the original string is shorter than "maxlen", it is returned verbatim
  294.      * @return the modified string
  295.      * @since 3.2
  296.      */
  297.     static QString rEmSqueeze( const QString & name,
  298.                                const QFontMetrics& fontMetrics,
  299.                                uint maxlen = 30 );
  300.  
  301.     /** Substitute characters at the end of a string by "...". Similar to
  302.      * method above, except that maxlen is the width in pixels to truncate to
  303.      * @param name is the string to modify
  304.      * @param fontMetrics is the font metrics to use to calculate character sizes
  305.      * @param maxPixels is the maximum pixel length the modified string will have
  306.      * If the original string is shorter than "maxlen", it is returned verbatim
  307.      * @return the modified string
  308.      * @since 3.2
  309.      */
  310.     static QString rPixelSqueeze( const QString & name,
  311.                                   const QFontMetrics& fontMetrics,
  312.                                   uint maxPixels );
  313.  
  314.     /**
  315.      * Match a filename.
  316.      * @param filename is the real decoded filename (or dirname
  317.      *        without trailing '/').
  318.      * @param pattern is a pattern like *.txt, *.tar.gz, Makefile.*, *README*, etc.
  319.      * Patterns with two asterisks like "*.*pk" are not supported.
  320.      * @return true if the given filename matches the given pattern
  321.      */
  322.     static bool matchFileName( const QString& filename, const QString& pattern );
  323.     // KDE4: move to KShell
  324.  
  325.     /**
  326.      * Split a QString into a QStringList in a similar fashion to the static
  327.      * QStringList function in Qt, except you can specify a maximum number
  328.      * of tokens. If max is specified (!= 0) then only that number of tokens
  329.      * will be extracted. The final token will be the remainder of the string.
  330.      *
  331.      * Example:
  332.      * \code
  333.      * perlSplit("__", "some__string__for__you__here", 4)
  334.      * QStringList contains: "some", "string", "for", "you__here"
  335.      * \endcode
  336.      *
  337.      * @param sep is the string to use to delimit s.
  338.      * @param s is the input string
  339.      * @param max is the maximum number of extractions to perform, or 0.
  340.      * @return A QStringList containing tokens extracted from s.
  341.      */
  342.     static QStringList perlSplit
  343.       (const QString & sep, const QString & s, uint max = 0);
  344.  
  345.     /**
  346.      * Split a QString into a QStringList in a similar fashion to the static
  347.      * QStringList function in Qt, except you can specify a maximum number
  348.      * of tokens. If max is specified (!= 0) then only that number of tokens
  349.      * will be extracted. The final token will be the remainder of the string.
  350.      *
  351.      * Example:
  352.      * \code
  353.      * perlSplit(' ', "kparts reaches the parts other parts can't", 3)
  354.      * QStringList contains: "kparts", "reaches", "the parts other parts can't"
  355.      * \endcode
  356.      *
  357.      * @param sep is the character to use to delimit s.
  358.      * @param s is the input string
  359.      * @param max is the maximum number of extractions to perform, or 0.
  360.      * @return A QStringList containing tokens extracted from s.
  361.      */
  362.     static QStringList perlSplit
  363.       (const QChar & sep, const QString & s, uint max = 0);
  364.  
  365.     /**
  366.      * Split a QString into a QStringList in a similar fashion to the static
  367.      * QStringList function in Qt, except you can specify a maximum number
  368.      * of tokens. If max is specified (!= 0) then only that number of tokens
  369.      * will be extracted. The final token will be the remainder of the string.
  370.      *
  371.      * Example:
  372.      * \code
  373.      * perlSplit(QRegExp("[! ]", "Split me up ! I'm bored ! OK ?", 3)
  374.      * QStringList contains: "Split", "me", "up ! I'm bored, OK ?"
  375.      * \endcode
  376.      *
  377.      * @param sep is the regular expression to use to delimit s.
  378.      * @param s is the input string
  379.      * @param max is the maximum number of extractions to perform, or 0.
  380.      * @return A QStringList containing tokens extracted from s.
  381.      */
  382.     static QStringList perlSplit
  383.       (const QRegExp & sep, const QString & s, uint max = 0);
  384.  
  385.     /**
  386.      * This method auto-detects URLs in strings, and adds HTML markup to them
  387.      * so that richtext or HTML-enabled widgets (such as KActiveLabel)
  388.      * will display the URL correctly.
  389.      * @param text the string which may contain URLs
  390.      * @return the resulting text
  391.      * @since 3.1
  392.      */
  393.     static QString tagURLs( const QString& text );
  394.  
  395.     /**
  396.       Obscure string by using a simple symmetric encryption. Applying the
  397.       function to a string obscured by this function will result in the original
  398.       string.
  399.  
  400.       The function can be used to obscure passwords stored to configuration
  401.       files. Note that this won't give you any more security than preventing
  402.       that the password is directly copied and pasted.
  403.  
  404.       @param str string to be obscured
  405.       @return obscured string
  406.       @since 3.2
  407.     */
  408.     static QString obscure( const QString &str );
  409.  
  410.     /**
  411.       Guess whether a string is UTF8 encoded.
  412.  
  413.       @param str the string to check
  414.       @return true if UTF8. If false, the string is probably in Local8Bit.
  415.       @since 3.2
  416.      */
  417.     static bool isUtf8( const char *str );
  418.  
  419.     /**
  420.       Construct QString from a c string, guessing whether it is UTF8- or
  421.       Local8Bit-encoded.
  422.  
  423.       @param str the input string
  424.       @return the (hopefully correctly guessed) QString representation of @p str
  425.       @since 3.2
  426.      */
  427.     static QString from8Bit( const char *str );
  428.  
  429. #ifdef KDE_NO_COMPAT
  430. private:
  431. #endif
  432.     /**
  433.      * @deprecated Use matchFileName () instead.
  434.      */
  435.     static KDE_DEPRECATED bool matchFilename( const QString& filename, const QString& pattern )
  436.     {
  437.         return matchFileName (filename, pattern);
  438.     }
  439.  
  440. };
  441. #endif
  442.